Using the SequeLink^® Proxy Server

Untrusted applets cannot open a connection to a machine other than the originating host. Therefore, if any JDBC Client will be used by an untrusted applet, your SequeLink Server software must be installed on the same machine as your Web server software. This is a Java restriction. To circumvent this restriction, SequeLink provides a component written in Java that you can install on your Web server host called the SequeLink Proxy Server.

Installing the SequeLink Proxy Server on the Web server from which your JDBC applets are downloaded allows untrusted applets to connect to SequeLink Servers on hosts other than the Web server, as shown in Figure 14-1.

Figure 14-1. SequeLink Proxy Server Installed on a Web Server

The SequeLink Proxy Server maps incoming TCP/IP connection requests from the JDBC Client to outgoing TCP connections to other hosts. When the SequeLink Proxy Server receives a connection request on a particular TCP/IP port, the SequeLink Proxy Server establishes a TCP/IP connection to a remote host and transfers data packets between the JDBC Client and the remote host.

In addition, you can use SSL encryption with the proxy server to encrypt data between the SequeLink Proxy Server and the JDBC Client. You can also use SSL with a Java application running on your Intranet to secure data over your entire network by installing the SequeLink Proxy Server on the same machine as the SequeLink Server. For example, you may want to use SSL to encrypt the data sent between an application server and the data store serviced by a SequeLink Server on another machine. See "Using SSL Encryption" for more information about SSL.

Configuring the SequeLink^® Proxy Server

Each SequeLink service serviced by the SequeLink Proxy Server must be described in a configuration file, service_name.cfg, where service_name is the name of the service. We recommend that the service name be the same as the SequeLink service it is servicing. Configuration files are stored in the proxy server directory and use the following keyword=value pairs:

Port	The incoming TCP/IP port. The JDBC applet or application must specify this TCP/IP port (and the IP address of the Proxy Server host) in the JDBC connection string.
ServerPort	The TCP/IP port of the service to which the final connection is made. This port must be the same port defined in the service configuration on the remote host. A default SequeLink service installation uses the port 19996.
Host	The IP address of the remote host or a symbolic host name.
AdminPort	The TCP/IP port on which the SequeLink Proxy Server listens for administration requests (for example, requests to stop the SequeLink Proxy Server). NOTE: If you do not want the SequeLink Proxy Server to listen for administration requests, omit this keyword from the configuration file. For example, if the SequeLink Proxy Server is installed on a Web server that is accessible by the Internet, your firewall may be configured to block requests from the Internet to the proxy server administration port.

You can find a configuration file template (proxyserver.cfg) in the proxy server directory. The configuration file must be located in the directory from which you start or stop the SequeLink Proxy Server.

Configuration File Example:

Port=4000 
ServerPort=4003 
Host=189.23.5.132 
AdminPort=5000 

NOTES:

Keywords in the configuration file are case-sensitive.
Make sure that you use different port numbers for the Port and AdminPort keywords. Also, the port numbers for the Port and AdminPort keywords must be unique (cannot be used by another TCP/IP service).


On Windows, you can use the SequeLink Manager to obtain the TCP/IP ports used by SequeLink services. In addition, you can verify the TCP/IP ports in the system32\etc\drivers\services file.


On Linux and UNIX, you can verify the TCP/IP ports in /etc/services.

Starting and Stopping the SequeLink^® Proxy Server

This section provides instructions for starting and stopping the SequeLink Proxy Server.

Starting the SequeLink^® Proxy Server

On Windows:

Open a command-line window and change the working directory to the proxy server directory. Start the SequeLink Proxy Server by running the command appropriate for the Java Virtual Machine (JVM) you are using:

proxyserver14 -s [-v jview] configfile

where configfile is the name of the proxy server configuration file without the .CFG extension. By default, this batch file uses the J2SE JVM. If you want to use the Microsoft JVM, specify the optional parameter -v jview as shown in the preceding example.

On Linux/UNIX:

Start the SequeLink Proxy Server by running the shell script: appropriate for the JVM you are using:

proxyserver14.sh -s [-v jview] configfile

where configfile is the name of the proxy server configuration file without the .CFG extension. The configuration file must be located in the directory from which you start or stop the SequeLink Proxy Server.

Stopping the SequeLink^® Proxy Server

On Windows servers:

Open a command-line window and change the working directory to the proxy server directory. Stop the SequeLink Proxy Server by running the command appropriate for the JVM you are using:

proxyserver14 -q [-v jview] configfile

where configfile is the name of the proxy server configuration file without the .CFG extension. By default, this BAT file uses the J2SE JVM. If you want to use the Microsoft JVM, specify the optional parameter -v jview as shown in the preceding example.

On Linux/UNIX:

Stop the SequeLink Proxy Server by running the shell script appropriate for the JVM you are using:

proxyserver14.sh -q [-v jview] configfile

where configfile is the name of the proxy server configuration file without the .CFG extension. The configuration file must be located in the directory from which you start or stop the SequeLink Proxy Server.

SequeLink^® Proxy Server Logging

All messages generated by the SequeLink Proxy Server are written to a log file in the installdir/proxy/log/ directory, where installdir is your installation directory. The log file name has the format:

proxy_server_name.log

where proxy_server_name is the name of the SequeLink Proxy Server. Severe errors and information, such as server started or server stopped messages display on the screen also.

Using the SequeLink^® Proxy Server as a Windows Service

Before you install the SequeLink Proxy Server as a Windows service, check the following requirements:

Make sure that you have administrator rights. Installing and un-installing the SequeLink Proxy Server as a Windows service requires making changes to the HKEY_LOCAL_MACHINE key in the Windows Registry.
Make sure that the directory your JVM is installed and is specified in the correct sequence in the system definition of the PATH environment variable. Because the SequeLink Proxy Server Windows service is configured to run under the local system account, access to network resources is not available. If the system definition of the PATH environment variable contains a network directory before the directory in which the JVM is installed, you will not be able to start the SequeLink Proxy Server.

If you cannot start the SequeLink Proxy Server, either:

Redefine the system definition of the PATH environment variable so that the network directory appears in the system definition after the directory in which the JVM is installed. Then, reboot to make your changes effective for the local system account.
Change the definition of the SequeLink Proxy Server Windows service to run under an account that has access to the specific network drive.
Make sure the CLASSPATH environment variable is defined correctly for your JVM and that the SequeLink Proxy Server .jar files are added to the CLASSPATH.

Installing the SequeLink Proxy Server as a Windows Service

Create a proxy server configuration file.
Open a Windows command window and change the working directory to the proxy subdirectory of the SequeLink Client for JDBC directory.
Issue the following command:

cmdsrvc -s service_name -c -r [-v jview]

where service_name is the name of the proxy server configuration file. This command creates a Windows service for the SequeLink Proxy Server. Use the Windows Event Viewer to verify that the service was created successfully (in the Application log for the source cmdsrvc). By default, the JDK JVM is used. If you want to use the Microsoft JVM, specify the optional parameter -v jview as shown in the preceding example.

The Windows service you created should have the following attributes:

Automatic startup
Log on as System Account
Allow service to interact with the desktop

In addition, a Windows Event Viewer source is defined with the name of the SequeLink Proxy Server. The SequeLink Proxy Server logs start and stop messages to this source.

Start the Windows service using the Windows Services control panel. Because the service is configured for automatic startup, it will also start when the Windows machine is initialized.

NOTE: Make sure that the following files located in the proxy/lib directory are added to the CLASSPATH definition of your JVM:

For a SequeLink Proxy Server running in...	Add these files to the CLASSPATH of your JVM...
J2SE Platform JVM without SSL	slproxy.jar
J2SE Platform JVM with SSL or data scrambling enabled	slproxy.jar, slssl14.jar, and iaik_jce_full.jar

Un-Installing the SequeLink^® Proxy Server as a Window Service

Before you un-install the SequeLink Proxy Server as a Windows service, make sure that you have administrator rights.

To un-install the SequeLink Proxy Server:

Stop the SequeLink Proxy Server Windows service using the Windows Services control panel.
Open a Windows command-line window.
Change the working directory to the proxy server subdirectory in the SequeLink Client for JDBC directory.
Issue the following command:

cmdsrvc -s service_name -d